ParcelLabel API

How to generate parcel labels for parcels using Fliway service

When generating parcel labels for packages using Fliway service, merchants are able to place Fliway jobs through our NZ Post API suite. Fliway will perform the delivery.

Fliway service needs to be enabled by NZ Post before a merchant can use the service. Please contact your NZ Post account manager to activate the service you require.

Resource URL

UAT:

https://api.uat.nzpost.co.nz/parcellabel/v3/labels

Production:

https://api.nzpost.co.nz/parcellabel/v3/labels

A unique consignment_id is returned once the details of the request are stored in the labeling database. One or multiple labels can be generated within a consignment (for Fliway Courier only), connote id for Fliway is generated as part of tracking numbers following the pattern NZP[0-9]{9}.

Request Parameters

For each of these services, the parameter requirements are similar but each service has slightly different requirements and needs to use the relevant service code. In the following table, we have provided which fields are required in the label request for a particular service.

Code samples for each of these separate service types are displayed further down this page.

Fliway Addons

The following are available Fliway addons.

Fliway Add-on Rules

The following rules apply to add-on services included in a label request:

1. Add-on services can only be present when the carrier is Fliway.
2. All parcel addons and return indicator must be the same when the carrier is Fliway.

Example 1: Fliway Return label for a single parcel (174x100mm)

{
    "carrier": "FLIWAY",
    "orientation": "landscape",
    "label_dimensions": "174x100",
    "account_number": "91671234",
    "format": "PDF",
    "despatch_date": "2024-10-30T09:00:00",
    "sender_reference_1": "Order1234",
    "paper_dimensions": {
        "width_cm": 15,
        "height_cm": 10
    },
    "sender_details": {
        "name": "Test Sender",
        "phone": "12345678",
        "email": "john.doe@nzpost.co.nz",
        "company_name": "NZ Post",
        "site_code": 96306
    },
    "pickup_address": {
        "address_id": 12345,
        "company_name": "TEST COMPANY",
        "xstreet": "122 Kerwyn avenue",
        "xsuburb": "East Tamaki",
        "xcity": "Auckland",
        "xstate": "AUK",
        "country_code": "NZ",
        "xpostcode": "2013",
        "FullAddressWithNameAndCompany": "NZ Post test company",
        "instructions": "test test 12345"
    },
    "receiver_details": {
        "name": "test receiver",
        "phone": "022345678",
        "email": "john.doe@nzpost.co.nz"
    },
    "delivery_address": {
        "is_collection": false,
        "building_name": "Test Delivery Building Name",
        "company_name": "Test Delivery Company Name",
        "street": "58 Eskdale Road",
        "suburb": "Papakowhai",
        "city": "Porirua",
        "country_code": "NZ",
        "postcode": "5024",
        "instructions": "Ask for Bubba at the reception."
    },
    "parcel_details": [
        {
            "service_code": "FLWY",
            "add_ons": ["FLHD","FLSR"],
            "return_indicator": "RETURN",
            "description": "MY PERSIHABLE TEST",
            "insured_valued_amount": 0,
            "currency": "nzd",
            "dimensions": {
                "length_cm": 100.0,
                "weight_kg": 31,
                "width_cm": 149.0,
                "height_cm": 10
            }
        }
    ]
}

Response Parameters

Sample Response

{

  "consignment_id": "DVZQYF",

  "message_id": "520f4fa0-22cc-11eb-b1e1-027414412442",

  "success": true

}

\`\`\`